home *** CD-ROM | disk | FTP | other *** search
Text File | 1998-07-16 | 20.8 KB | 459 lines | [TEXT/MPS ] |
- InputSprocket 1.3
- Release Notes
- -------------------
- General Release Notes:
-
- Although not a change, a clarification is needed on how exclusive items operate
- particularly with regards to hat-type switches (direction-pads, digital
- joysticks and hat switches). A group of mutually exclusive items is a group of
- items where activation of one item automatically deactivates other items in the
- group. A group of mutually exclusive items might be assigned to a hat. An
- example is "look" functionality which allows the user to different directions
- from the cockpit in a flight simulator implemented as four different button
- needs. A problem will arise if the group of items only uses the activation of
- these buttons to select which item is active. This problem will only arise if
- the program in question does not properly handle combinations of the button
- activations.
-
- For example, if I assign "look right" to the right item of a hat and "look
- forward" to the top item of a hat. Now, if I press right on the hat I will look
- right. If I now wiggle my thumb upwards so that up is activated (up and right
- are now simultaneously activated) I will look forward. If I slide my thumb back
- to the right, I will release the "look up" item, but since the "look right"
- item was activated the whole time, I do not reactivate the "look right"
- function. I now have my thumb holding the hat right, but I am looking forward.
-
- In fact, since the "look right" item is already held down, it is the ONLY
- button on the entire controller which cannot be pressed and it becomes
- impossible to look right without releasing the hat and pressing it right again.
- Symptoms of this are that it is easier to look right by pressing forward and
- sliding right to the corner of the d-pad than it is to press right directly!
-
- The only way to correct for this is to consider both presses (kISpButtonDown)
- and releases (kISpButtonUp) of any button needs which are exclusive. In this
- case, when right is pressed, the right function would be activated. When the up
- function is activated, both items are now activated. The InputSprocket client
- can either deactivate the original right function and switch to the up
- function, or it can remain with the right function and only switch to the up
- function when the right button is released. If the hat is moved to the right
- again and the up function is released, then the client should switch back to
- the right function if it has switched away.
-
- Proper handling of releases for button needs will allow mutually exclusive
- functions to operate properly.
-
- Before you ship any application, check to make sure you get no warnings when
- running with InputSprocketDebugLib and the debug versions of the drivers.
-
- Changes from 1.2
- -----------------
-
- A resource definition file "InputSprocket.r" has been added. You can use this
- file to create a Rez '.r' file to build the ISp resources into your
- application.
-
- One of the templates is for the 'tset' resource created by the ISp keyboard
- driver. Note this templete is ONLY valid for a 'tset' generated by the
- keyboard. The only way to tell who created the 'tset' is to examine the 'setl'
- resource that points to it. The new sample code for DroneZone uses this
- template so that the defaults for the keyboard are in a Rez file and are
- easily updated when then application's list of needs changes. You still have
- recreate the sets for mice and gaming devices when your needs list changes
- during development, but not having to re-setup all the keyboard keys every
- time should be a big win. (Note: You may have to delete your InputSprocket
- Preferences file in order to get the new defaults from the application -- or
- change the subCreatorCode passed to ISpInit.)
-
- New drivers have been added:
- InputSprocket CH Trackball: support for CH Trackballs
- InputSprocket Contour: support for the Contour Mouse
- InputSprocket MicroSpeed: support for MacTRAC and MouseDeluxe
- InputSprocket NoHands: support for the NoHands mouse
- InputSprocket ArenaMouse: support for the 'Arena' 3D mouse
- InputSprocket MacALLY: support for the MacALLY Joystick
- InputSprocket USB: support for some USB devices on a Mac with USB
-
- Special thanks to Jeremy Erwin who is not affiliated with MacALLY, for the
- code to support the MacALLY stick.
-
- In the debug folder, there is a new driver:
- InputSprocket NeedView: useful for debugging your application
-
- All mice and keyboard drivers are 'passthru' in the debug versions. This
- means that it is VERY important you make sure you also test with the release
- versions of the drivers, since some things will work fine with the debug
- versions but not with the release drivers. On the other hand, you will never
- get stuck in the debugger without being able to type and/or move the cursor.
-
- InputSprocket resets all elements to 'zero' values (symmetric axis are
- reset to the center) across suspend/resume. It is the responsibility of
- individual ISp drivers to push data to any elements which are non-default
- valued when the driver is reactivated.
-
- ISp drivers must insure that they are Virtual Memory (VM) safe.
- InterruptTickle is only called at 'VM safe' times. However, ISp drivers must
- be aware of any callbacks they install directly, and whether they can occur
- during 'VM unsafe' times. If so then the ISp Driver is responsible for
- insuring that it is memory resident. Drivers which use ADB can include
- InputSprocketDefer.h and link to InputSprocketDeferLib which provides services
- so that ADB handlers are deferred until paging safe time. This way, the driver
- does not have to be held (although it will be resident under most conditions
- if it is actually being called many times a second). Drivers which use USB
- via USBHIDUniversalModule will automatically be deferred until 'VM safe'
- times, so do not have to worry about this problem.
-
- Many minor bugs have been fixed.
-
- 68K support has been added. 68K InputSprocket is only available through
- CFM-68K.
-
- Some new constants were added to InputSprocket.h.
-
- InputSprocket 1.2
- Release Notes
- -----------------
-
- General Release Notes:
-
- This release involves many minor improvements to the InputSprocket drivers,
- including an improved user interface (UI) for axis. Some new drivers have
- also been added. Several problems and bugs have been addressed.
-
- A new resource has been defined (kISpApplicationResourceType = 'isap') which
- all
- applications which use InputSprocket should put (ID 0) in their resource fork.
- They should always set bit 0 (kISpAppResFlag_UsesInputSprocket) and set bit 1
- (kISpAppResFlag_UsesISpInit) if they use the high level API (ie they call
- ISpInit, ISpConfig, etc... in other words they have a needs list). The rest of
- the bits and reserved fields should be set to 0.
-
- A new ISpElementKind has been added: kISpElementKind_Delta which specifies
- a Fixed point number of inches moved. InputSprocket Mouse and
- InputSprocket Kensington now register elements of this kind in the low level.
- The high level (through ISpConfigure) supports axis as well as delta kinds.
- This kind is very useful if you want to control a cursor.
-
- A new definition of ISpNeed can be used by defining USE_OLD_ISPNEED_STRUCT to
- 0.
- The first reserved field (a short) was changed to two UInt8s: playerNum and
- group. Use playerNum to tell the driver some needs are related to a particular
- player (on the same machine). The SprocketInvaders source code will be reved to
- use this field. Group is used to group items together, such as a look up, look
- down need (assuming you can't use an axis). You should also group items
- together
- that have the same effect, but are 'tuned' button, axis, and delta versions.
- The
- current ISp drivers do not use this hinting, yet. Some new definitions for the
- ISpNeedFlagBits have been added. If you use the new definition, make sure you
- check your code for cases where you were initializing the struct. You now may
- be misaligned, and many compilers will NOT generate a warning.
-
- High Level Release Notes:
-
- InputSprocket needs a 640x480 display (or larger) in order for its dialog to
- work.
- If you are asking DrawSprocket for a smaller display size than that you should
- switch out before calling InputSprocket.
-
- Information about how to get saved sets ('setl' Resources) to work is below
- under the InputSprocket 1.0 Release Notes
-
- AbsoluteTime and UnsignedWide are in the latest types.h (ETO #20 or later).
- /*typedef UnsignedWide AbsoluteTime; struct UnsignedWide {UInt32 hi;UInt32
- lo;};*/
-
- InputSprocket Mouse supplies pseudo-buttons in the high level for modifier
- keys in combination with mouse clicks. You will have at least four buttons
- (where some may actually be command/shift/control/option-click on
- one-button mice) for any mouse device. This should make it straightforward
- to port games which expect a two button mouse: use ISp with delta and
- button needs -- and dont worry about what type of device the user has.
-
- Changes from 1.1
- -----------------
- - InputSprocket Speech added back to distribution (crashing bug fixed)
- - InputSprocket Gravis supports Blackhawk and uses new UI (new save set format)
- - InputSprocket Thrustmaster uses new UI (new save set format)
- - InputSprocket Joy completely revised, renamed InputSprocket CH, now supports
- multiple devices seperately and supports up to 8 buttons and 4 hats per device
- (new save set format)
- - InputSprocket Kensington added, supports kensington devices regardless
- of their software
- - InputSprocket Sidewinder 3D Pro added, supports Microsoft Sidewinder joystick
- - InputSprocket AppleJack added, supports Pippin/AppleJack controller
- - InputSprocket Keyboard supports modifier keys in conjunction with a normal
- key
- (now either Escape or Cmd-Q are valid for kISpElementLabel_Btn_PauseResume)
- - Device and element strings have been reviewed, and some have been changed
- - ISpConfigure saves and restores the port.
- - A new function: ISpTimeToMicroseconds has been added.
- - There are some new bits defined for ISpNeedFlagBits.
- - Some new element labels have been added.
- - Old saved sets for devices other than mouse and keyboard do not work
-
- Incomplete list of devices input sprocket supports
- --------------------------------------------------
- - Thrustmaster FCS, Thrustmaster WCS, Thrustmaster RCS
- - Gravis Gamepad, Gravis Firebird, Gravis Mousestick II, Gravis Blackhawk
- - CH Jetstick, CH Flightstick Pro, CH Pro Pedals, CH Pedals, CH F16
- Fighterstick, CH Gamepad, CH Pro Throttle
- - Kensington TurboMouse 4.0, TurboMouse 5.0, Thinking Mouse,
- Kensington Mouse, CoStar Stringray trackball
- - Microsoft SideWinder 3D Pro
- - AppleJack/ Pippin Controller
- - Speech Recognition
- - Keyboard
- - traditional Apple 'id handler 1' mouse and 100% compatable mice
- - modern 'id handler 4' mice including Logitech Trackman Marble (see the
- technote "Space Aliens Ate My Mouse")
-
- Known Problems in 1.2
- ---------------------
- - Kensington Mouse-in-a-box reports two buttons (only the first one works)
- - ALPS GlidePoint does not appear if ALPS software is installed (appears w/o
- ALPS software)
- - Mouse Systems Mouse does not appear if Mouse Systems software ('3-Button
- Power') is installed (appears as 1 button mouse w/o Mouse Systems software)
- - CH Trackball PRO does not appear
- - Thrustmaster software generates keyDowns if so configured with ThrustWare
- (fix
- is to configure all buttons to do nothing in ThrustWare)
- - Machines based on the Tanzania motherboard (Motorola StarMax, APS MPower,
- Apple PowerMacintosh 4400) will always show an extra Mouse device for the
- PS/2 mouse regardless whether one is plugged in (even though the 4400 has
- no PS/2 ports, the phantom ADB devices for them are still created). The
- PS/2 mouse only reports one button.
- - When a Sidewinder 3D Pro stick is connected, an extra mouse device is shown
- which is active when the 'mouse/joystick' switch is switched to 'mouse'.
- - It is unstable to have multiple applications use InputSprocket
- simultaneously. If your application can be suspended and uses InputSprocket
- you should use ISpShutdown and ISpStartup so that InputSprocket is off while
- you are in the background. This is a bug (since 1.0) and will be fixed
- in the next version. If you are a user you can work around this problem
- by not running more than one InputSprocket application at the same time.
- - When debugging, you may need to deactivate the Mouse and Keyboard drivers in
- order to be able to interact with your debugger.
-
- InputSprocket 1.1
- Release Notes
- -----------------
-
- General Release Notes:
- We recommend that if you are using input sprocket version greater than 1.02
- that
- you no longer support any third party joystick APIs.
- You must not support those APIs at the same time as you have InputSprocket
- devices enabled.
-
- High Level Release Notes:
- If you are using InputSprocket via the high level (ISpConfigure and ISpInit and
- so on). We recommend that you only use the axis and button data types and
- build
- the controls that you need out of those types. This will get you the best
- support. Many of the drivers are going to only primarily emulate those
- datatypes.
-
-
- Known Problems in 1.1
- ---------------------
- - Kensington Trackball does not appear if Kensington software is installed
- (appears w/o Kensington software)
- - ALPS GlidePoint does not appear if ALPS software is installed (appears w/o
- ALPS software)
- - Mouse Systems Mouse does not appear if Mouse Systems software ('3-Button
- Power') is installed (appears as 1 button mouse w/o Mouse Systems software)
- - CoStar Stingray Trackball does not appear if CoStar software ('Stingray') is
- installed (appears w/o CoStar software)
- - CH Trackball PRO does not appear
- - Thrustmaster software generates keyDowns if so configured with ThrustWare
- (fix
- is to configure all buttons to do nothing in ThrustWare)
-
- Changes from 1.02
- -----------------
- - new APIs (ISpStartup, ISpShutdown, ISpTickle, ISpDevices_ActivateClass,
- ISpDevices_DeactivateClass)
- - some general ui improvements in both appearance and performance have been
- made
- - new driver InputSprocket Joy (supports some features of JoyManager devices --
- ie mainly CH products)
- - new driver InputSprocket Thrustmaster (supports FCS, WCS, RCS)
- - new driver InputSprocket Gravis (supports MouseStick, Firebird, GamePad)
- - new driver InputSprocket Speech (you must activate explicitly and requires
- ISpTickle be called)
- - InputSprocket Mouse changed to have new UI and is implemented via ADBMgr
- directly instead of a CursorDeviceMgr Patch
- - InputSprocket Keyboard has been slightly changed if there is only one page
- - driver function to plot icons has been changed (faster)
- - bug when you select a 0 length name to save a set has been fixed
- - bug involving choosing monitor has been fixed (might chose something other
- than the main monitor randomly)
- - CH Flightstick, CH Gamepad, CH Jetstick and MacEnjoy no longer generate a
- mouse device
- - a crashing bug involving multiple applications using input sprocket
- simultaniously has been fixed
- - a very small memory leak involving ISpConfigure has been fixed
- - DONT_USE_OLD_INPUT_SPROCKET_LABELS changed to USE_OLD_INPUT_SPROCKET_LABELS
- in
- InputSprocket.h
- - a bug where InputSprocket Keyboard and InputSprocket Mouse called InitGraf
- has
- been fixed
-
- InputSprocket Speech Notes
- --------------------------
- - you must call ISpTickle in order for InputSprocket Speech to work
- - you must call ISpDevices_ActivateClass(kISpDeviceClass_SpeechRecognition) to
- turn InputSprocket Speech on
- - requires SpeechRecognition extension 1.5.1 (PlainTalk 1.5)
-
- InputSprocket Joy Notes
- -----------------------
- - supports all JoyManager devices as a single input sprocket device.
- - UI may show popups for controls the device does not have
- - JoySimpleData based
- - only supports the trigger and three additional buttons
- - digital pointing devices (ex. CH Gamepad's pad) are treated as a pair of axis
- not a POV Hat
-
- InputSprocket 1.02
- Release Notes
- -----------------
-
- There is a new InputSprocket.h that has new versions of the names for the
- labels
- as well as additional labels.
-
- The following bugs were fixed in the 1.01 or the 1.02 releases.
- - keyboard ui now generates better names than Min/Max for axis if ElementLabel
- is useful
- - various problems with alignment and growing of dialog were fixed
- - flickering with icons in thrustmaster and mouse fixed
- - stub library included in this release with file type 'stub'
- - axis flipping check box now works again for the mouse driver
- - ISpDevices_Extract functions no work when an exact count is passed to them
- - Icon plotting is more robust.
- - The OK button is no longer hilited when the keyboard is active.
- - InputSprocket will now unload the drivers when the last fragment is unloaded
- - InputSprocket no longer leaks memory when you quit in the suspended state
- - when there are no devices to configure and ISpConfigure is called it will
- display a warning instead of doing nothing
- - ISpSuspend no longer leaks 10,000 bytes every call
-
- The following bugs are known:
- -There is an incompatability with the mouse driver and the Kensignton trackball
- software that causes no mice devices to appear.
- -There is a incompatability with the Kensington trackball that causes an extra
- mouse device to appear when the hardware is installed and the software is not
- installed.
-
- InputSprocket 1.0
- Release Notes
- -----------------
-
- Please report all bugs to sprockets@adr.apple.com!
-
- Release Components
- ------------------
-
- InputSprocket Release Notes - this file
- InputSprocket.h - the header file to compile with
- InputSprocketLib - release version of the library
- InputSprocketDebugLib - debugging version of the library
- InputSprocketStubLib - version of the library to link to
- InputSprocket Keyboard - keyboard plug-in
- InputSprocket Mouse - mouse plug-in
- InputSprocketTest - test program
- InputSprocketTest.ยต - Metrowerks 8 project to build test
- InputSprocketTest Sources - sources for test program
-
- Place InputSprocket Keyboard, InputSprocket Mouse and InputSprocketLib or
- InputSprocketDebugLib in the Extensions folder. Place InputSprocket.h in
- your development environment's C Headers folder. Place InputSprocketStubLib
- in your development environment's Libraries folder.
-
- WARNING: don't place both the debugging and non-debugging versions of the
- library in the search path or you will not be sure which version you will be
- using.
-
- Dependencies
- ------------
-
- InputSprocket requires the latest Universal Headers -- version 2.1.2 or later.
- You can find them on E.T.O. #20, the MacOS SDK CD-ROMs, Apple's web-site, or
- a number of other locations. If you have a problem with the "AbsoluteTime"
- type usage, then you aren't using the latest Types.h file.
-
- Compatability with Prereleases
- ------------------------------
-
- InputSprocket 1.0 is not compatible with any of the pre-release versions of
- InputSprocket. You should throw out all DR versions.
-
- Changes to 'setl' Resource
- --------------------------
-
- The format for the set list resource ('setl') was changed at the last minute.
- A resedit TMPL resource is automatically installed in the preference file and
- the format is as follows:
-
- -- header --
- Version (4 bytes) The current version is now 2.
- Count (4 bytes)
-
- -- each entry --
- name (64 bytes) A pascal string
- set length (4 bytes) The length of the set
- device class (4 bytes) The device class of the device
- device identifier (4 bytes) The device identifier of the device
- flags (4 bytes) Same flags as in the header
- reserved1 (4 bytes) Reserved by apple set to zero.
- reserved2 (4 bytes) Reserved by apple set to zero.
- reserved3 (4 bytes) Reserved by apple set to zero.
- set resource id (2 bytes) The resource id of the set.
- reserved4 (2 bytes) Reserved by apple set to zero.
-
- Special Considerations
- ----------------------
-
- - Your game should use the Escape key to pause and resume play. The
- element that corresponds to the Escape key is labelled
- ISpElementLabel_Start. If your game uses virtual elements then the
- first button need that is labelled ISpElementLabel_Start is auto-
- configured to the Escape key, and the user can't change this in
- the ISpConfigure dialog.
-
- - Your game may provide default and optional configurations for the
- keyboard, the mouse and any other devices. This is done by including
- 'setl' and 'tset' resources a resource file, such as the application's,
- that is open when ISpInit and ISpConfigure are called. Since the
- format of the 'tset' resource is determined by the device, it is
- easiest to use the configuration dialog to establish the desired
- configurations then copy them from the Preferences file into your
- resource file.
-
- 1. Remove the InputSprocket Preferences file from the Preferences
- folder.
-
- 2. Run your game, and invoke the ISpConfigure dialog.
-
- 3. Configure and save as many sets as you like for any and all
- devices.
-
- 4. Quit.
-
- 5. Use ResEdit to move the 'setl' and 'tset' resources to your
- resource file.
-
- 6. Edit the 'setl' resource using the 'TMPL' supplied in
- InputSprocketSimpleTest.rsrc.
-
- 7. Change the flags field to $00000002 for the default entry for
- a given device or $00000004 for any other entry for that
- device.
-
- 8. Again remove the InputSprocket Preferences file from the
- Preferences folder so you can test with a clean slate.
-
- 9. Rebuild your game and try out your new configurations.
-